This is the documentation of the \texttt{MODULE NonNum}, a set
of \texttt{FORTRAN 90} routines to sort and search. This module make
use of the \texttt{MODULE NumTypes}, and \texttt{MODULE Error} so
please read the documentation of these modules \emph{before} reading
this. 

\section{Subroutine \texttt{Swap(X,Ind1,Ind2)}}
\index{Swap@Subroutine \texttt{Swap(X,Ind1,Ind2)}}

\subsection{Description}

Swaps elements \texttt{Ind1} and \texttt{Ind2} of the array
\texttt{X(:)}. 

\subsection{Arguments}

\begin{description}
\item[\texttt{X(:)}: ] Integer, real single or real double precision one
  dimensional array. \emph{Note that
    $X$ is overwritten when calling this routine}. 
\item[\texttt{Ind1, Ind2}: ] Integer. The elements that we want to
  permute. 
\end{description}

\subsection{Examples}

\begin{lstlisting}[emph=Swap,
                   emphstyle=\color{blue},
                   frame=trBL,
                   caption=Sorting data.,
                   label=swap]
Program TestNN

  USE NumTypes
  USE NonNumeric

  Integer, Parameter :: Nmax = 10
  Integer :: Ima(Nmax), I


  ! Fill Ima(:) 
  Forall (I=1:Nmax) Ima(I) = I

  ! Plot the numbers
  Do I = 1, Nmax
     Write(*,'(1000I10)')Ima(I)
  End Do

  ! Swap first and last elemetns of Ima(:) and plot them.
  CALL Swap(Ima, 1, Nmax)
  Write(*,*)'# With first and last elements permuted: '
  Do I = 1, Nmax
     Write(*,'(1000I10)')Ima(I)
  End Do


  Stop
End Program TestNN
\end{lstlisting}

\section{Subroutine \texttt{Insrt(X[, Ipt])}}
\index{Insrt@Subroutine \texttt{Insrt(X[, Ipt])}}

\subsection{Description}

Sort the elements of \texttt{X(:)} in ascendant order\footnote{This
  routine uses \emph{insertion sort}, and is much slower than
  \texttt{Qsort}. To sort more than 10 elements, use \texttt{Qsort}
  unless you know what you are doing.}. 

\subsection{Arguments}

\begin{description}
\item[\texttt{X(:)}: ] Integer, real single or real double precision one
  dimensional array. Initially it contains unsorted numbers, and after
  calling the routine, it contains the sorted elements. \emph{Note that
    $X$ is overwritten when calling this routine}. 
\item[\texttt{Ipt(:)}: ] Integer vector, Optional. It returns the
  permutation made to \texttt{X(:)} to sort it.
\end{description}

\subsection{Examples}

\begin{lstlisting}[emph=Insrt,
                   emphstyle=\color{blue},
                   frame=trBL,
                   caption=Sorting data.,
                   label=insrt]
Program TestNN

  USE NumTypes
  USE NonNumeric

  Integer, Parameter :: Nmax = 10
  Integer :: Ima(Nmax)
  Real (kind=DP) :: X(Nmax), Y(Nmax)


  ! Fill X(:) with random data, and define Y(:)
  CALL Random_Number(X)
  Y = Sin(12.34_DP*(X-0.5_DP))

  ! Plot an unsorted data table
  Do I = 1, Nmax
     Write(*,'(1000ES13.5)')X(I), Y(I)
  End Do

  ! Sort them, and plot the table again. Same points, but this time
  ! sorted 
  CALL Insrt(X, Ima)
  Write(*,*)'# Again, this time sorted: '
  Do I = 1, Nmax
     Write(*,'(1000ES13.5)')X(I), Y(Ima(I))
  End Do


  Stop
End Program TestNN
\end{lstlisting}


\section{Subroutine \texttt{Qsort(X[, Ipt])}}
\index{Qsort@Subroutine \texttt{Qsort(X[, Ipt])}}

\subsection{Description}

Sort the elements of \texttt{X(:)} in ascendant order.

\subsection{Arguments}

\begin{description}
\item[\texttt{X(:)}: ] Integer, real single or real double precision one
  dimensional array. Initially it contains unsorted numbers, and after
  calling the routine, it contains the sorted elements. \emph{Note that
    $X$ is overwritten when calling this routine}. 
\item[\texttt{Ipt(:)}: ] Integer vector, Optional. It returns the
  permutation made to \texttt{X(:)} to sort it.
\end{description}

\subsection{Examples}

\begin{lstlisting}[emph=Qsort,
                   emphstyle=\color{blue},
                   frame=trBL,
                   caption=Sorting data.,
                   label=qsort]
Program TestNN

  USE NumTypes
  USE NonNumeric

  Integer, Parameter :: Nmax = 10
  Integer :: Ima(Nmax)
  Real (kind=DP) :: X(Nmax), Y(Nmax)


  ! Fill X(:) with random data, and define Y(:)
  CALL Random_Number(X)
  Y = Sin(12.34_DP*(X-0.5_DP))

  ! Plot an unsorted data table
  Do I = 1, Nmax
     Write(*,'(1000ES13.5)')X(I), Y(I)
  End Do

  ! Sort them, and plot the table again. Same points, but this time
  ! sorted 
  CALL Qsort(X, Ima)
  Write(*,*)'# Again, this time sorted: '
  Do I = 1, Nmax
     Write(*,'(1000ES13.5)')X(I), Y(Ima(I))
  End Do


  Stop
End Program TestNN
\end{lstlisting}


\section{Function \texttt{Locate(X, $\mathtt{X_0}$[, Iin])}}
\index{Locate@Function \texttt{Locate(X, $\mathtt{X_0}$[, Iin])}}

\subsection{Description}

Given a \emph{sorted} vector of elements \texttt{X(:)}, and a point
$\mathtt{X_0}$, \texttt{Locate} returns the position $n$ such that
$\mathtt{X(n)<X_0<X(n+1)}$. If  $\mathtt{X_0}$ is less than all the
elements of $\mathtt{X(:)}$, \texttt{Locate} returns $0$, and if it is
greater than all the elements of $\mathtt{X(:)}$, it returns the
number of elements of $\mathtt{X(:)}$

\subsection{Arguments}

\begin{description}
\item[\texttt{X(:)}: ] Integer, real single or real double precision one
  dimensional \emph{sorted} array. 
\item[$\mathtt{X_0}$: ] Integer, real single or real double precision
  number, but the same type as $\mathtt{X(:)}$. Point that we want to
  locate in the sorted vector $\mathtt{X(:)}$.
\item[\texttt{Iin}: ] Integer, Optional. Initial guess of the position.
\end{description}

\subsection{Output}

Integer. The position $n$ such that 
\begin{displaymath}
  \mathtt{X(n)<X_0<X(n+1)}  
\end{displaymath}

\subsection{Examples}

\begin{lstlisting}[emph=Locate,
                   emphstyle=\color{blue},
                   frame=trBL,
                   caption=Searching data position in an ordered list.,
                   label=locate]
Program TestNN

  USE NumTypes
  USE NonNumeric

  Integer, Parameter :: Nmax = 100
  Integer :: Ima(Nmax), Idx
  Real (kind=DP) :: X(Nmax), Y(Nmax), X0


  ! Fill X(:) with random data, and set X0 to some arbitrary value. 
  CALL Random_Number(X)
  X0 = 0.276546754_DP

  ! Sort X(:), find the position of X0, and plot the neightborr
  ! elements. 
  CALL Qsort(X)
  Idx = Locate(X, X0)
  Write(*,'(1A,1ES33.25)')'Searched element: ', X0
  Write(*,'(1A,1ES33.25)')'Previous element in the list: ', X(Idx)
  Write(*,'(1A,1ES33.25)')'Next element in the list:     ', X(Idx+1)

  Stop
End Program TestNN
\end{lstlisting}

\section{Function \texttt{NumberOfLines(fname)}}
\index{NumberOfLines@Function \texttt{NumberOfLines(fname)}}

\subsection{Description}

Returns the numbr of lines in file \texttt{fname}.

\subsection{Arguments}

\begin{description}
\item[\texttt{fname}: ] Character (len=*). A file name.
\end{description}

\subsection{Output}

Integer. The number of lines of file \texttt{fname}

\subsection{Examples}

\begin{lstlisting}[emph=NumberOfLines,
                   emphstyle=\color{blue},
                   frame=trBL,
                   caption=Obtainning the number of columns of a file.,
                   label=nol]
Program TestNN

  USE NumTypes
  USE NonNumeric

  Write(*,*)NumberOfLines('foo.dat')

  Stop
End Program TestNN
\end{lstlisting}


\section{Function \texttt{NumberOfColumns(fname)}}
\index{NumberOfColumns@Function \texttt{NumberOfColumns(fname)}}

\subsection{Description}

Returns the numbr of columns of file \texttt{fname}.

\subsection{Arguments}

\begin{description}
\item[\texttt{fname}: ] Character (len=*). A file name.
\end{description}

\subsection{Output}

Integer. The number of columns of file \texttt{fname}.

\subsection{Examples}

\begin{lstlisting}[emph=NumberOfColumns,
                   emphstyle=\color{blue},
                   frame=trBL,
                   caption=Obtainning the number of columns of a file.,
                   label=nol]
Program TestNN

  USE NumTypes
  USE NonNumeric

  Write(*,*)NumberOfColumns('foo.dat')

  Stop
End Program TestNN
\end{lstlisting}

\section{Function \texttt{Hash(buf)}}
\index{Hash@Function \texttt{Hash(buf)}}

\subsection{Description}

Returns a hash for the array of integers \texttt{buf(:)}. The code
uses a random table lookup to provide an fast and efficient hash. Use
the transfer function to hash arbitrary data.

\subsection{Arguments}

\begin{description}
\item[\texttt{buf(:)}: ] Integer one dimensional array. Data to
  compute the hash.
\end{description}

\subsection{Output}

Integer. The number of columns of file \texttt{fname}.

\subsection{Examples}

\begin{lstlisting}[emph=NumberOfColumns,
                   emphstyle=\color{blue},
                   frame=trBL,
                   caption=Checksum of data in a structure.,
                   label=nol]
Program Checksum
 
  USE NonNumeric
 
  Type data
     Real (kind=DP) :: C(200)
     Integer :: N
     Character (len=100) :: Comment
  End type data
 
  Type (data) :: ex(200000)
  Integer, Allocatable :: buf(:)
  Integer :: I, J
 
  Allocate(buf(Size(Transfer(ex, buf))))
  buf = Transfer(ex, buf)
 
  Write(*,*)Hash(buf)
 
  Stop
End Program Checksum
\end{lstlisting}

\section{Subroutine \texttt{WriteBuffer(buf,fn,[comment])}}
\index{WriteBuffer@Function \texttt{WriteBuffer(buf,fn,[comment])}}

\subsection{Description}

Writes a header with date and checksum and the data from
\texttt{buf(:)} in binary in file \texttt{fn}. Use
the transfer function to store arbitrary data.

\subsection{Arguments}

\begin{description}
\item[\texttt{buf(:)}: ] Integer one dimensional array. Data to
  store in a file.
\item[\texttt{fn}: ] Character (len=*). File name to store data.
\item[\texttt{Comment[(:)]}: ] Character (len=*) or an array of
  them. Possible information to store in ASCII in the metadata section.
\end{description}

\subsection{Examples}

\begin{lstlisting}[emph=NumberOfColumns,
                   emphstyle=\color{blue},
                   frame=trBL,
                   caption=Stoing data on a file.,
                   label=nol]
Program Checksum
 
  USE NonNumeric
 
  Type data
     Real (kind=DP) :: C(200)
     Integer :: N
     Character (len=100) :: Comment
  End type data
 
  Type (data) :: ex(200000)
  Integer, Allocatable :: buf(:)
  Integer :: I, J
 
  Allocate(buf(Size(Transfer(ex, buf))))
  buf = Transfer(ex, buf)
 
  CALL WriteBuffer(buf,'ex.data','Silly data, but big file')
 
  Stop
End Program Checksum
\end{lstlisting}

\section{Subroutine \texttt{ReadBuffer(buf,fn)}}
\index{ReadBuffer@Function \texttt{ReadBuffer(buf,fn)}}

\subsection{Description}

Reads data of file \texttt{fn}, checks the checksum and return the
bits in an array of integers. Use
the transfer function to store arbitrary data.

\subsection{Arguments}

\begin{description}
\item[\texttt{buf(:)}: ] Integer one dimensional allocatable
  array. Stores the data after reading the file.
\item[\texttt{fn}: ] Character (len=*). File name with data.
\end{description}

\subsection{Examples}

\begin{lstlisting}[emph=NumberOfColumns,
                   emphstyle=\color{blue},
                   frame=trBL,
                   caption=Reading data from file.,
                   label=nol]
Program Checksum
 
  USE NonNumeric
 
  Type data
     Real (kind=DP) :: C(200)
     Integer :: N
     Character (len=100) :: Comment
  End type data
 
  Type (data) :: ex(200000)
  Integer, Allocatable :: buf(:)
  Integer :: I, J
 
  CALL WriteBuffer(buf,'ex.data')
  ex = Transfer(buf, ex)
 
  CALL WriteBuffer(buf,'ex.data','Silly data, but big file')
 
  Stop
End Program Checksum
\end{lstlisting}

\section{Function \texttt{GetOpt(opt, [val])}}
\index{GetOpt@Function \texttt{GetOpt(opt,[val])}}

\subsection{Description}

Check if command line argument \texttt{opt} is present, and if this is
the case returs the value in val. 

\subsection{Arguments}

\begin{description}
\item[\texttt{opt}: ] Character (len=*). An command line option.
\item[\texttt{val}: ] Integer, Real simple or double
  precision. Optional. Returns the value of the command line option.
\end{description}

\subsection{Output}

Logical. \texttt{.True.} is \texttt{opt} is present as a command line
argument, \texttt{.False.} otherwise.

\subsection{Examples}

\begin{lstlisting}[emph=GetOpt,
                   emphstyle=\color{blue},
                   frame=trBL,
                   caption=Obtainning command line arguments.,
                   label=nol]
Program OPT

  USE NumTypes
  USE NonNumeric

  Integer :: NN
  Character (len=10) :: aa
  Real (kind=SP) :: r
  Real (kind=DP) :: d


  If (GetOpt('-i', NN)) Then
     Write(*,*)'Valor del argumento -i: ', NN
  Else
     Write(*,*)'Argumento -i no esta presente'
  End If

  If (GetOpt('-c', aa)) Then
     Write(*,*)'Valor del argumento -c: ', aa
  Else
     Write(*,*)'Argumento -c no esta presente'
  End If

  If (GetOpt('-s', r)) Then
     Write(*,*)'Valor del argumento -s: ', r
  Else
     Write(*,*)'Argumento -s no esta presente'
  End If

  If (GetOpt('-d', d)) Then
     Write(*,*)'Valor del argumento -d: ', d
  Else
     Write(*,*)'Argumento -d no esta presente'
  End If

  If (GetOpt('-h')) Then
     Write(*,*)' Usage: opt.x [options]'
     Write(*,*)'   -i int'
     Write(*,*)'   -c character string'
     Write(*,*)'   -s real'
     Write(*,*)'   -d double'
     Write(*,*)'   -h'
  End If

  Stop
End Program OPT
\end{lstlisting}


% Local Variables: 
% mode: latex
% TeX-master: "lib"
% End: 
